1 Tag object
In this basic tutorial, we run through all the steps of GeoPressureR using only pressure data, with the simple example of a Swainson’s Warbler. This bird presents a short migration route, with only a few stopovers, making it fast to compute.
1.1 Create tag
What is a tag object?
A tag refers to a geolocator or datalogger device that can contain multiple sensors (e.g., pressure, light, acceleration).
In GeoPressureR, tag is an essential object (i.e., a S3 class) modified at each step of the workflow: not only does it store the raw logger data, but it also aggregates all the information needed to ultimately be able to model the bird’s trajectory.
The tag object is created based on the raw geolocator data
tag <- tag_create(
id = "CB619",
pressure_file = "*.deg",
light_file = NULL,
acceleration_file = NULL
)## ✔ Read './data/raw-tag/CB619//CB619.deg'The raw data for this tag id should be stored in "./data/raw-tag/CB619/" following the default structure described in GeoPressureTemplate. Because the data are recorded with a Migrate Technology tag, we use the file extension pressure_file = "*.deg".
You can use the generic plot() function to visualize the tag data.
plot(tag, type = "pressure")Depending on when you equipped the bird and when your tag started recording data, you will likely need to crop your data to specific dates. As it is bad practice to modify your raw data, we recommend using the crop_start and crop_end arguments in tag_create().
1.2 Label tag into stationary periods
Labelling tracks involves two steps:
- Label periods of flight, which, by extension will define the STAtionary Periods (called
stapin the code), during which the bird is assumed to remain at the same location (+/- tens of kilometers) and same elevation level (+/- few meters) - Discard pressure measurements which should not be used to estimate position (due to, for example, sensor error, flight, minor/short changes in elevation level, etc.)
Important note
Correctly labelling the track requires time and effort, but is key to accurately estimate the bird’s position.
As labelling relies on functions and tools presented later in the tutorial, we recommend first following the basic and advanced tutorials. After that, we strongly advise that you read attentively the recommendations for this step provided in labelling tracks.
1.2.1 Initialize and create the label .csv file
Use tag_label_write() to initiate the label (i.e., empty label) and create the label file to "./data/tag-label/CB619.csv".
tag_label_write(tag)## ℹ No label data.
## → Initialize automatically label using
## `tag_label_auto()`## ✔ './data/tag-label/CB619.csv' written successfully.1.2.2 Label manually on Trainset
Open https://trainset.raphaelnussbaumer.com/ and click on “Upload Tag Label” to load your .csv file. Instructions on how to label the file can be found in the dedicated chapter labelling tracks. Once you have finished, export the new csv file in the same folder /data/tag-label/CB619-labeled.csv (TRAINSET will automatically add -labeled in the name).
1.2.3 Read labelled file
Read the exported file with tag_label_read() to update tag$pressure (and, when relevant, tag$acceleration), with a new label column.
tag <- tag_label_read(tag)
knitr::kable(head(tag$pressure), format = "html")| date | value | label |
|---|---|---|
| 2021-07-01 02:30:10 | 954.2268 | |
| 2021-07-01 03:00:10 | 954.0889 | |
| 2021-07-01 03:30:10 | 953.8978 | |
| 2021-07-01 04:00:10 | 953.6862 | |
| 2021-07-01 04:30:10 | 953.4887 | |
| 2021-07-01 05:00:10 | 953.0179 |
1.2.4 Compute stationary periods
tag_label_stap() then creates the stationary periods based on these labels:
tag <- tag_label_stap(tag)##
## ── Short stationary periods:
## ✔ All 9 stationary periods duration are above 6 hours.
##
## ── Short flights:
## ✔ All 8 flights duration are above 2 hours.| stap_id | start | end |
|---|---|---|
| 1 | 2021-07-01 02:30:10 | 2021-09-24 00:00:10 |
| 2 | 2021-09-24 11:30:10 | 2021-09-24 23:30:10 |
| 3 | 2021-09-25 11:00:10 | 2021-09-25 23:30:10 |
| 4 | 2021-09-26 13:00:10 | 2021-09-27 04:00:10 |
| 5 | 2021-09-27 08:30:10 | 2022-04-06 00:30:10 |
| 6 | 2022-04-06 10:30:10 | 2022-04-07 00:00:10 |
Plotting the pressure timeseries of tag provides additional information:
plot(tag, type = "pressure")##
## ── Pre-processed pressure data length
## ✔ All stationary periods have more than 12 datapoints.
##
## ── Pressure difference
## ✔ All hourly changes in pressure are below 3 hPa.What is pre-processing?
You might notice some discrepancies between the raw data (grey) and the pre-processed pressure timeseries of each stationary period (colored lines).
The pre-processing aligns the raw timeseries data to the weather reanalysis pressure data, by removing ouliers and downscaling the resolution to 1hr falling on the exact hour.
The black dots show the discarded pressure points (i.e., ouliers), corresponding to bird vertical movement rather than natural variation of pressure.
Once you have created the tag label file (i.e., CB619-labeled.csv), you can use directly tag_label() to read the label and compute stationary periods.